<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>WebScarab QA, sourcecode maintenance, draft</title>
</head>
<body>
<h1>abstract</h1>
This document describes the tools and methods used to keep
the java sourcecode of the WebScarab project clean, well-formed
and functional. As for now it is a draft and still needs to
be reviewed, extended and approved.
<h1>tools / libraries</h1>
<table>
<tr>
  <th align="left">purpose</th>
  <th align="left">name</th>
  <th align="left">revision</th>
  <th align="left">download location</th>
</tr>
<tr>
  <td>building projects</td>
  <td>ant</td>
  <td>1.4.1</td>
  <td>http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/src/jakarta-ant-1.4.1-src.tar.gz</td>
</tr>
<tr>
  <td>testing code</td>
  <td>junit</td>
  <td>3.7</td>
  <td>http://download.sourceforge.net/junit/junit3.7.zip</td>
</tr>

</table>
<h1>writing code</h1>
If some piece of code requires technical specifications of any
kind, the tech spec must be written and approved by the developer
team BEFORE the implementation process begins.<br />
If it shows up, that some interface must be changed, this has
to be announced. Again, the tech specs have to be rewritten first,
after approval interfaces may be changed.<br />
To assure that any piece of code is working exactly as one expects,
junit tests are used.<br /> The general contract is <b>to write tests first</b>,
i.e. once you defined some interface ("interface" means members,
methods and ctors of any class that have <code>public</code> scope)
you should define it's behaviour by writing explicit tests for it.<br />
<b>Example</b><br />
<code><pre>
class Foo {
  int _x;
  public Foo () {}
  public int get() { }
  public Object doSomething( Object val ) {}
}</pre></code><br />
Now let us assume you want the following behaviour:
<ul>
<li>a new Foo is initialized with x = 2</li>
<li>doSomething never returns null</li>
<li>every call to doSomething increments x</li>
</ul>
You would write junit tests like this:<br />
<code><pre>
void testInit () {
  Foo f = new Foo();
  assertEquals( 2, f.get() );
}

void testDoNotNull () {
  Foo f = new Foo();
  assertNotNull(  f.doSomething( null ) );
}

void testDoInc () {
  Foo f = new Foo();
  f.doSomething( "val" );
  assertEquals( 3, f.get() );
  f.doSomething( "val" );
  assertEquals( 4, f.get() );
}
</pre></code>

Now <b>AFTER</b> having defined the behaviour of the interface
you implement it:<br />
<code><pre>
class Foo {
  int _x;
  public Foo () { _x = 2; }
  public int get() { return _x; }
  public Object doSomething( Object val ) { return null == val ? "null" : val; }
}</pre></code><br />

Everything alright?<br />NO!<br />
Surely you noticed that the last test will fail, since _x is not 
incremented on doSomething().<br />
By writing the test first you will discover immediately that something
goes wrong.<br />

If you do it this way around it is more likely that you do not forget to
test for a behaviour that you want to have.<br />

<h1>requirements for "stable" branches / releases</h1>
Until the first major release, no backwards compatibility for obsolete
interfaces will be provided.<br />
After the first major stable release, old interfaces have to be
maintained exactly for the next following minor release.<br />
Old interfaces have to be marked as deprecated and MUST BE REMOVED
AND SUBSTITUTED COMPLETELY with the next minor release.<br />
Only sourcecode that fulfils the following requirements  will be allowed
 to be published in "stable" releases or to be commited in "stable" CVS
 branches:
<ul>
<li>complete test suite for the interface</li>
<li>complete jdoc for the interface</li>
<li>digitally signed (reviewed) by at least two developers</li>
</ul>
The last point is some assurance for the case that a developer who
wrote some awfully efficient, but yet cryptic code suddenly disappears.<br />
If every class (sourcefile) is at least known and understood by two
<i>active</i> developers, one can be sure that every part of the whole
system can be maintained by somebody.

<h1>source code format</h1>
<ul>
<li>exactly one tab per indentation level</li>
<li>members start with an underscore, local var's don't</li>
<li>complete jdoc</li>
<li></li>
</ul>

<h1>packaging</h1>
These are the rules for package naming:
<ul>
<li>every package is a subpackage of <code>org.owasp.webscarab</code></li>
<li>generic utility package: org.owasp.webscarab.util</li>
<li>datastore main package: org.owasp.webscarab.data</li>
<li>analyser main package: org.owasp.webscarab.analyse</li>
<li>spider main package: orq.owasp.webscarab.spider</li>
<li>attack generator main package: org.owasp.webscarab.attack</li>
<li>browser proxy main package: org.owasp.webscarab.proxy</li>
<li>client app main package: org.owasp.webscarab.ui</li>
</ul>
Every package may depend on ...util.<br />
All interfaces used to exchange data between the main packages must
be declared in the main packages and NOT in any subpackages.<br />




</body>
</html>
